スケーラブル・アロケーターの C インターフェイス

[memory_allocation.scalable_alloc_c_interface]

スケーラブルなメモリー割り当て用の低レベル・インターフェイス。

// <oneapi/tbb/scalable_allocator.h> ヘッダーで定義 

extern "C" { 
// Scalable analogs of C memory allocator 
void* scalable_malloc( size_t size ); 
void scalable_free( void* ptr ); 
void* scalable_calloc( size_t nobj, size_t size ); 
void* scalable_realloc( void* ptr, size_t size ); 
// Analog of _msize/malloc_size/malloc_usable_size. 
size_t scalable_msize( void* ptr ); 
// Scalable analog of posix_memalign 
int scalable_posix_memalign( void** memptr, size_t alignment, size_t size ); 
// Aligned allocation 
void* scalable_aligned_malloc( size_t size, size_t alignment); 
void scalable_aligned_free( void* ptr ); 
void* scalable_aligned_realloc( void* ptr, size_t size, size_t alignment ); 
// Return values for scalable_allocation_* functions 
typedef enum { TBBMALLOC_OK, TBBMALLOC_INVALID_PARAM, TBBMALLOC_UNSUPPORTED, TBBMALLOC_NO_MEMORY, TBBMALLOC_NO_EFFECT } ScalableAllocationResult; 
typedef enum { 
// To turn on/off the use of huge memory pages 
TBBMALLOC_USE_HUGE_PAGES, 
// To set a threshold for the allocator memory usage.// Exceeding it will forcefully clean internal memory buffers 
TBBMALLOC_SET_SOFT_HEAP_LIMIT, 
// Lower bound for the size (Bytes), that is interpreted as huge 
// and not released during regular cleanup operations 
TBBMALLOC_SET_HUGE_SIZE_THRESHOLD } AllocationModeParam; 
// Set allocator-specific allocation modes. 
int scalable_allocation_mode(int param, intptr_t value); 
typedef enum { 
// Clean internal allocator buffers for all threads.TBBMALLOC_CLEAN_ALL_BUFFERS, 
// Clean internal allocator buffer for current thread only.TBBMALLOC_CLEAN_THREAD_BUFFERS } ScalableAllocationCmd; 
// Call allocator-specific commands. 
int scalable_allocation_command(int cmd, void *param); 
}

これらの関数は、スケーラブル・アロケーターへの C レベルのインターフェイスを提供します。scalable_allocation_mode および scalable_allocation_command を除き、scalable_x ルーチンはそれぞれ x ライブラリー関数と同じように動作します。下記の表 「スケーラブル・アロケーターへの C インターフェイス」 に示されているように、ルーチンには 2 つのファミリーがあります。あるファミリーの scalable_x 関数で割り当てられたストレージ領域は、C 標準ライブラリー関数ではなく、同じファミリーの scalable_x 関数で解放またはサイズを変更する必要があります。同様に、C 標準ライブラリー関数で割り当てられた記憶領域は、scalable_x 関数で解放またはサイズを変更してはなりません。

次の関数は、メモリーを実際に割り当てたり解放することはありませんが、有用な情報を取得したりメモリー・アロケーターの動作に影響することはあります。

size_t scalable_msize(void *ptr)

戻り値: ptr がスケーラブル・アロケーターで割り当てられたメモリーブロックを指している場合、メモリーブロックの使用可能なサイズを返します。ptr がそのようなブロックを指していない場合は 0 を返します。。

int scalable_allocation_mode(int mode, intptr_t value)

この関数は、スケラーブル・メモリー・アロケーターの動作を調整するために使用されます。

戻り値: 操作に成功した場合は TBBMALLOC_OK を返しますが、mode が次のいずれでもない、または value が指定されたモードで有効でない場合は TBBMALLOC_INVALID_PARAM を返します。次に示すように、ほかの戻り値も可能です。

scalable_allocation_mode パラメーター: パラメーター、説明

TBBMALLOC_USE_HUGE_PAGES

scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 1) は、オペレーティング・システムによって有効にされる場合、ヒュージページを使用するようにアロケーターに指示します。scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 0) ではそれを無効にします。TBB_MALLOC_USE_HUGE_PAGES 環境変数を 1 に設定すると、scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 1) を呼び出すのと同じ効果があります。scalable_allocation_mode() で設定されたモードは環境変数よりも優先されます。

期待される戻り値: ヒュージページがサポートされていない場合、TBBMALLOC_NO_EFFECT が返ります。

現在、この割り当てモードは Linux* でのみサポートされます。これは、明示的に構成されたヒュージページと透過的なヒュージページの両方で動作します。ヒュージページの有効化と構成については、OS のドキュメントを参照するかシステム管理者に問い合わせてください。

TBBMALLOC_SET_SOFT_HEAP_LIMIT

scalable_allocation_mode(TBBMALLOC_SET_SOFT_HEAP_LIMIT, size) は、アロケーターが OS から取得するメモリー使用量のしきい値を size バイトで設定します。しきい値を超えると、アロケーターは内部バッファーからメモリーを解放するようになります。ただし、必要な追加メモリーの要求を妨げるものではありません。

TBBMALLOC_SET_HUGE_SIZE_THRESHOLD

scalable_allocation_mode(TBBMALLOC_SET_HUGE_SIZE_THRESHOLD, size) は、size の下限となるしきい値を設定します (バイト単位)。このしきい値よりも大きなオブジェクトはヒュージとなり、内部の定期的なクリーンアップ・ロジックには含まれません。ただし、TBBMALLOC_SET_SOFT_HEAP_LIMIT モードのロジックや、TBBMALLOC_CLEAN_ALL_BUFFERS 操作には影響しません。

TBB_MALLOC_SET_HUGE_SIZE_THRESHOLD 環境変数を size 値に設定しても同様の効果がありますが、LONG_MAX 値に制限されます。scalable_allocation_mode で設定されたモードは環境変数よりも優先されます。

int scalable_allocation_command(int cmd, void *reserved)

この関数は、最初の引数で指定された動作を実行するようスケーラブル・メモリー・アロケーターに指示するコマンドとして使用されます。2 番目の引数は予約済みであり 0 でなければなりません。

戻り値: 操作に成功した場合は TBBMALLOC_OK を返し、cmd が次のいずれでもない、または reserved が 0 でない場合は TBBMALLOC_INVALID_PARAM を返します。

scalable_allocation_command パラメーター: パラメーター、説明

TBBMALLOC_CLEAN_ALL_BUFFERS

scalable_allocation_command(TBBMALLOC_CLEAN_ALL_BUFFERS, 0) は、アロケーター内部のメモリーバッファーをクリーンアップするため、メモリーのフットプリントを減らす可能性があります。これにより、後続のメモリー割り当て要求にかかる時間が増えます。このコマンドは頻繁に使用されることを想定していません。パフォーマンスに与える影響を慎重に評価することを推奨します。

期待される戻り値:: バッファーが解放されなかった場合、TBBMALLOC_NO_EFFECTを返します。

注

未使用のメモリーがすべて解放されるとは限りません。

TBBMALLOC_CLEAN_THREAD_BUFFERS

scalable_allocation_command(TBBMALLOC_CLEAN_THREAD_BUFFERS, 0) は、呼び出しスレッドの内部メモリーバッファーのみをクリーンアップします。

期待される戻り値:: バッファーが解放されなかった場合 TBBMALLOC_NO_EFFECT を返します。